<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>17.6. Standard Form Elements Shipped With Zend Framework</title>
<link rel="stylesheet" href="dbstyle.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.72.0">
<link rel="start" href="index.html" title="Programmer's Reference Guide">
<link rel="up" href="zend.form.html" title="Chapter 17. Zend_Form">
<link rel="prev" href="zend.form.decorators.html" title="17.5. Creating Custom Form Markup Using Zend_Form_Decorator">
<link rel="next" href="zend.form.standardDecorators.html" title="17.7. Standard Form Decorators Shipped With Zend Framework">
<link rel="chapter" href="introduction.html" title="Chapter 1. Introduction to Zend Framework">
<link rel="chapter" href="zend.acl.html" title="Chapter 2. Zend_Acl">
<link rel="chapter" href="zend.auth.html" title="Chapter 3. Zend_Auth">
<link rel="chapter" href="zend.cache.html" title="Chapter 4. Zend_Cache">
<link rel="chapter" href="zend.config.html" title="Chapter 5. Zend_Config">
<link rel="chapter" href="zend.console.getopt.html" title="Chapter 6. Zend_Console_Getopt">
<link rel="chapter" href="zend.controller.html" title="Chapter 7. Zend_Controller">
<link rel="chapter" href="zend.currency.html" title="Chapter 8. Zend_Currency">
<link rel="chapter" href="zend.date.html" title="Chapter 9. Zend_Date">
<link rel="chapter" href="zend.db.html" title="Chapter 10. Zend_Db">
<link rel="chapter" href="zend.debug.html" title="Chapter 11. Zend_Debug">
<link rel="chapter" href="zend.dojo.html" title="Chapter 12. Zend_Dojo">
<link rel="chapter" href="zend.dom.html" title="Chapter 13. Zend_Dom">
<link rel="chapter" href="zend.exception.html" title="Chapter 14. Zend_Exception">
<link rel="chapter" href="zend.feed.html" title="Chapter 15. Zend_Feed">
<link rel="chapter" href="zend.filter.html" title="Chapter 16. Zend_Filter">
<link rel="chapter" href="zend.form.html" title="Chapter 17. Zend_Form">
<link rel="chapter" href="zend.gdata.html" title="Chapter 18. Zend_Gdata">
<link rel="chapter" href="zend.http.html" title="Chapter 19. Zend_Http">
<link rel="chapter" href="zend.infocard.html" title="Chapter 20. Zend_InfoCard">
<link rel="chapter" href="zend.json.html" title="Chapter 21. Zend_Json">
<link rel="chapter" href="zend.layout.html" title="Chapter 22. Zend_Layout">
<link rel="chapter" href="zend.ldap.html" title="Chapter 23. Zend_Ldap">
<link rel="chapter" href="zend.loader.html" title="Chapter 24. Zend_Loader">
<link rel="chapter" href="zend.locale.html" title="Chapter 25. Zend_Locale">
<link rel="chapter" href="zend.log.html" title="Chapter 26. Zend_Log">
<link rel="chapter" href="zend.mail.html" title="Chapter 27. Zend_Mail">
<link rel="chapter" href="zend.measure.html" title="Chapter 28. Zend_Measure">
<link rel="chapter" href="zend.memory.html" title="Chapter 29. Zend_Memory">
<link rel="chapter" href="zend.mime.html" title="Chapter 30. Zend_Mime">
<link rel="chapter" href="zend.openid.html" title="Chapter 31. Zend_OpenId">
<link rel="chapter" href="zend.paginator.html" title="Chapter 32. Zend_Paginator">
<link rel="chapter" href="zend.pdf.html" title="Chapter 33. Zend_Pdf">
<link rel="chapter" href="zend.registry.html" title="Chapter 34. Zend_Registry">
<link rel="chapter" href="zend.rest.html" title="Chapter 35. Zend_Rest">
<link rel="chapter" href="zend.search.lucene.html" title="Chapter 36. Zend_Search_Lucene">
<link rel="chapter" href="zend.server.html" title="Chapter 37. Zend_Server">
<link rel="chapter" href="zend.service.html" title="Chapter 38. Zend_Service">
<link rel="chapter" href="zend.session.html" title="Chapter 39. Zend_Session">
<link rel="chapter" href="zend.soap.html" title="Chapter 40. Zend_Soap">
<link rel="chapter" href="zend.test.html" title="Chapter 41. Zend_Test">
<link rel="chapter" href="zend.text.html" title="Chapter 42. Zend_Text">
<link rel="chapter" href="zend.timesync.html" title="Chapter 43. Zend_TimeSync">
<link rel="chapter" href="zend.translate.html" title="Chapter 44. Zend_Translate">
<link rel="chapter" href="zend.uri.html" title="Chapter 45. Zend_Uri">
<link rel="chapter" href="zend.validate.html" title="Chapter 46. Zend_Validate">
<link rel="chapter" href="zend.version.html" title="Chapter 47. Zend_Version">
<link rel="chapter" href="zend.view.html" title="Chapter 48. Zend_View">
<link rel="chapter" href="zend.xmlrpc.html" title="Chapter 49. Zend_XmlRpc">
<link rel="appendix" href="requirements.html" title="Appendix A. Zend Framework Requirements">
<link rel="appendix" href="coding-standard.html" title="Appendix B. Zend Framework Coding Standard for PHP">
<link rel="appendix" href="copyrights.html" title="Appendix C. Copyright Information">
<link rel="index" href="the.index.html" title="Index">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.button" title="17.6.1. Zend_Form_Element_Button">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.checkbox" title="17.6.2. Zend_Form_Element_Checkbox">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.hidden" title="17.6.3. Zend_Form_Element_Hidden">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.hash" title="17.6.4. Zend_Form_Element_Hash">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.Image" title="17.6.5. Zend_Form_Element_Image">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.multiCheckbox" title="17.6.6. Zend_Form_Element_MultiCheckbox">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.multiselect" title="17.6.7. Zend_Form_Element_Multiselect">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.password" title="17.6.8. Zend_Form_Element_Password">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.radio" title="17.6.9. Zend_Form_Element_Radio">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.reset" title="17.6.10. Zend_Form_Element_Reset">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.select" title="17.6.11. Zend_Form_Element_Select">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.submit" title="17.6.12. Zend_Form_Element_Submit">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.text" title="17.6.13. Zend_Form_Element_Text">
<link rel="subsection" href="zend.form.standardElements.html#zend.form.standardElements.textarea" title="17.6.14. Zend_Form_Element_Textarea">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader"><table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">17.6. Standard Form Elements Shipped With Zend Framework</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="zend.form.decorators.html">Prev</a> </td>
<th width="60%" align="center">Chapter 17. Zend_Form</th>
<td width="20%" align="right"> <a accesskey="n" href="zend.form.standardDecorators.html">Next</a>
</td>
</tr>
</table></div>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="zend.form.standardElements"></a>17.6. Standard Form Elements Shipped With Zend Framework</h2></div></div></div>
<p>
        Zend Framework ships with concrete element classes covering most HTML
        form elements. Most simply specify a particular view helper for use when
        decorating the element, but several offer additional functionality. The
        following is a list of all such classes, as well as descriptions of the
        functionality they offer.
    </p>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.button"></a>17.6.1. Zend_Form_Element_Button</h3></div></div></div>
<p>
            Used for creating HTML button elements,
            <code class="code">Zend_Form_Element_Button</code> extends <a href="zend.form.standardElements.html#zend.form.standardElements.submit" title="17.6.12. Zend_Form_Element_Submit">Zend_Form_Element_Submit</a>,
            deriving its custom functionality. It specifies the 'formButton'
            view helper for decoration.
        </p>
<p>
            Like the submit element, it uses the element's label as the element
            value for display purposes; in other words, to set the text of the
            button, set the value of the element. The label will be translated
            if a translation adapter is present.
        </p>
<p>
            Because the label is used as part of the element, the button element
            uses only the <a href="zend.form.standardDecorators.html#zend.form.standardDecorators.viewHelper" title="17.7.11. Zend_Form_Decorator_ViewHelper">ViewHelper</a>
            and <a href="zend.form.standardDecorators.html#zend.form.standardDecorators.dtDdWrapper" title="17.7.3. Zend_Form_Decorator_DtDdWrapper">DtDdWrapper</a>
            decorators.
        </p>
<p>
            After populating or validating a form, you can check if the given
            button was clicked using the <code class="code">isChecked()</code> method.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.checkbox"></a>17.6.2. Zend_Form_Element_Checkbox</h3></div></div></div>
<p>
            HTML checkboxes allow you return a specific value, but basically
            operate as booleans: when it is checked, the value is submitted;
            when it's not checked, nothing is submitted. Internally,
            Zend_Form_Element_Checkbox enforces this state.
        </p>
<p>
            By default, the checked value is '1', and the unchecked value '0'.
            You can specify the values to use using the
            <code class="code">setCheckedValue()</code> and <code class="code">setUncheckedValue()</code>
            accessors, respectively. Internally, any time you set the value, if
            the provided value matches the checked value, then it is set, but
            any other value causes the unchecked value to be set.
        </p>
<p>
            Additionally, setting the value sets the <code class="code">checked</code>
            property of the checkbox. You can query this using
            <code class="code">isChecked()</code> or simply accessing the property. Using the
            <code class="code">setChecked($flag)</code> method will both set the state of the
            flag as well as set the approriate checked or unchecked value in the
            element. Please use this method when setting the checked state of a
            checkbox element to ensure the value is set properly.
        </p>
<p>
            <code class="code">Zend_Form_Element_Checkbox</code> uses the 'formCheckbox' view
            helper. The checked value is always used to populate it.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.hidden"></a>17.6.3. Zend_Form_Element_Hidden</h3></div></div></div>
<p>
            Hidden elements merely inject data that should be submitted, but
            which the user should not manipulate.
            <code class="code">Zend_Form_Element_Hidden</code> accomplishes this through use
            of the 'formHidden' view helper.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.hash"></a>17.6.4. Zend_Form_Element_Hash</h3></div></div></div>
<p>
            This element provides protection from CSRF attacks on forms,
            ensuring the data is submitted by the user session that generated
            the form and not by a rogue script. Protection is achieved by adding
            a hash element to a form and verifying it when the form is
            submitted.
        </p>
<p>
            The name of the hash element should be unique. It is recommended to use
            the <code class="literal">salt</code> option for the element, two hashes with
            same names and different salts would not collide:
        </p>
<pre class="programlisting">&lt;?php
$form-&gt;addElement('hash', 'no_csrf_foo', array('salt' =&gt; 'unique'));
?&gt;</pre>
<p>
            You can set the salt later using the <code class="code">setSalt($salt)</code>
            method.
        </p>
<p>
            Internally, the element stores a unique identifier using
            <code class="code">Zend_Session_Namespace</code>, and checks for it at
            submission (checking that the TTL has not expired). The 'Identical'
            validator is then used to ensure the submitted hash matches the
            stored hash.
        </p>
<p>
            The 'formHidden' view helper is used to render the element in the
            form.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.Image"></a>17.6.5. Zend_Form_Element_Image</h3></div></div></div>
<p>
            Images can be used as form elements, and allow you to specify
            graphical elements as form buttons.
        </p>
<p>
            Images need an image source. <code class="code">Zend_Form_Element_Image</code>
            allows you to specify this by using the <code class="code">setImage()</code>
            accessor (or 'image' configuration key). You can also optionally specify a value to use when
            submitting the image using the <code class="code">setImageValue()</code> accessor
            (or 'imageValue' configuration key). When the value set for the
            element matches the <code class="code">imageValue</code>, then the accessor
            <code class="code">isChecked()</code> will return true. 
        </p>
<p>
            The Image element uses the 
            <a href="zend.form.standardDecorators.html#zend.form.standardDecorators.image" title="17.7.9. Zend_Form_Decorator_Image">Image
                Decorator</a> for rendering (as well as the standard Errors,
            HtmlTag, and Label decorators). You can optionally specify a tag to
            the <code class="code">Image</code> decorator that will then wrap the image
            element.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.multiCheckbox"></a>17.6.6. Zend_Form_Element_MultiCheckbox</h3></div></div></div>
<p>
            Often you have a set of related checkboxes, and you wish to group
            the results. This is much like a <a href="zend.form.standardElements.html#zend.form.standardElements.multiselect" title="17.6.7. Zend_Form_Element_Multiselect">Multiselect</a>,
            but instead of them being in a dropdown list, you need to show
            checkbox/value pairs.
        </p>
<p>
            <code class="code">Zend_Form_Element_MultiCheckbox</code> makes this a snap. Like
            all other elements extending the base Multi element, you can specify
            a list of options, and easily validate against that same list. The
            'formMultiCheckbox' view helper ensures that these are returned as
            an array in the form submission.
        </p>
<p>
            You may manipulate the various checkbox options using the following
            methods:
        </p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="code">addMultiOption($option, $value)</code></p></li>
<li><p><code class="code">addMultiOptions(array $options)</code></p></li>
<li><p><code class="code">setMultiOptions(array $options)</code>
                    (overwrites existing options)</p></li>
<li><p>getMultiOption($option)</p></li>
<li><p>getMultiOptions()</p></li>
<li><p><code class="code">removeMultiOption($option)</code></p></li>
<li><p><code class="code">clearMultiOptions()</code></p></li>
</ul></div>
<p>
            To mark checked items, you need to pass an array of values to
            <code class="code">setValue()</code>. The following will check the values "bar"
            and "bat":
        </p>
<pre class="programlisting">
$element = new Zend_Form_Element_MultiCheckbox('foo', array(
    'multiOptions' =&gt; array(
        'foo' =&gt; 'Foo Option',
        'bar' =&gt; 'Bar Option',
        'baz' =&gt; 'Baz Option',
        'bat' =&gt; 'Bat Option',
    );
));

$element-&gt;setValue(array('bar', 'bat'));
</pre>
<p>
            Note that even when setting a single value, you must pass an array.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.multiselect"></a>17.6.7. Zend_Form_Element_Multiselect</h3></div></div></div>
<p>
            XHTML <code class="code">select</code> elements allow a 'multiple' attribute,
            indicating multiple options may be selected for submission, instead
            of the usual one. <code class="code">Zend_Form_Element_Multiselect</code> extends
            <a href="zend.form.standardElements.html#zend.form.standardElements.select" title="17.6.11. Zend_Form_Element_Select">Zend_Form_Element_Select</a>,
            and sets the <code class="code">multiple</code> attribute to 'multiple'. Like
            other classes that inherit from the base
            <code class="code">Zend_Form_Element_Multi</code> class, you can manipulate the
            options for the select using:
        </p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="code">addMultiOption($option, $value)</code></p></li>
<li><p><code class="code">addMultiOptions(array $options)</code></p></li>
<li><p><code class="code">setMultiOptions(array $options)</code>
                    (overwrites existing options)</p></li>
<li><p>getMultiOption($option)</p></li>
<li><p>getMultiOptions()</p></li>
<li><p><code class="code">removeMultiOption($option)</code></p></li>
<li><p><code class="code">clearMultiOptions()</code></p></li>
</ul></div>
<p>
            If a translation adapter is registered with the form and/or element,
            option values will be translated for display purposes.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.password"></a>17.6.8. Zend_Form_Element_Password</h3></div></div></div>
<p>
            Password elements are basically normal text elements -- except that
            you typically do not want the submitted password displayed in error
            messages or the element itself when the form is re-displayed.
        </p>
<p>
            <code class="code">Zend_Form_Element_Password</code> achieves this by calling
            <code class="code">setObscureValue(true)</code> on each validator (ensuring that
            the password is obscured in validation error messages), and using
            the 'formPassword' view helper (which does not display the value
            passed to it).
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.radio"></a>17.6.9. Zend_Form_Element_Radio</h3></div></div></div>
<p>
            Radio elements allow you to specify several options, of which you
            need a single value returned. <code class="code">Zend_Form_Element_Radio</code>
            extends the base <code class="code">Zend_Form_Element_Multi</code> class,
            allowing you to specify a number of options, and then uses the
            <code class="code">formRadio</code> view helper to display these.
        </p>
<p>
            Like all elements extending the Multi element base class, the
            following methods may be used to manipulate the radio options
            displayed:
        </p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="code">addMultiOption($option, $value)</code></p></li>
<li><p><code class="code">addMultiOptions(array $options)</code></p></li>
<li><p><code class="code">setMultiOptions(array $options)</code>
                    (overwrites existing options)</p></li>
<li><p>getMultiOption($option)</p></li>
<li><p>getMultiOptions()</p></li>
<li><p><code class="code">removeMultiOption($option)</code></p></li>
<li><p><code class="code">clearMultiOptions()</code></p></li>
</ul></div>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.reset"></a>17.6.10. Zend_Form_Element_Reset</h3></div></div></div>
<p>
            Reset buttons are typically used to clear a form, and are not part
            of submitted data. However, as they serve a purpose in the display,
            they are included in the standard elements.
        </p>
<p>
            <code class="code">Zend_Form_Element_Reset</code> extends <a href="zend.form.standardElements.html#zend.form.standardElements.submit" title="17.6.12. Zend_Form_Element_Submit">Zend_Form_Element_Submit</a>.
            As such, the label is used for the button display, and will be
            translated if a translation adapter is present. It utilizes only the
            'ViewHelper' and 'DtDdWrapper' decorators, as there should never be
            error messages for such elements, nor will a label be necessary.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.select"></a>17.6.11. Zend_Form_Element_Select</h3></div></div></div>
<p>
            Select boxes are a common way of limiting to specific choices for a
            given form datum. <code class="code">Zend_Form_Element_Select</code> allows you
            to generate these quickly and easily.
        </p>
<p>
            As it extends the base Multi element, the following methods may be
            used to manipulate the select options:
        </p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="code">addMultiOption($option, $value)</code></p></li>
<li><p><code class="code">addMultiOptions(array $options)</code></p></li>
<li><p><code class="code">setMultiOptions(array $options)</code>
                    (overwrites existing options)</p></li>
<li><p>getMultiOption($option)</p></li>
<li><p>getMultiOptions()</p></li>
<li><p><code class="code">removeMultiOption($option)</code></p></li>
<li><p><code class="code">clearMultiOptions()</code></p></li>
</ul></div>
<p>
            <code class="code">Zend_Form_Element_Select</code> uses the 'formSelect' view
            helper for decoration.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.submit"></a>17.6.12. Zend_Form_Element_Submit</h3></div></div></div>
<p>
            Submit buttons are used to submit a form. You may use multiple
            submit buttons; you can use the button used to submit the form to
            decide what action to take with the data submitted.
            <code class="code">Zend_Form_Element_Submit</code> makes this decisioning easy,
            by adding a <code class="code">isChecked()</code> method; as only one button
            element will be submitted by the form, after populating or
            validating the form, you can call this method on each submit button
            to determine which one was used.
        </p>
<p>
            <code class="code">Zend_Form_Element_Submit</code> uses the label as the "value"
            of the submit button, translating it if a translation adapter is
            present. <code class="code">isChecked()</code> checks the submitted value against
            the label in order to determine if the button was used.
        </p>
<p>
            The <a href="zend.form.standardDecorators.html#zend.form.standardDecorators.viewHelper" title="17.7.11. Zend_Form_Decorator_ViewHelper">ViewHelper</a>
            and <a href="zend.form.standardDecorators.html#zend.form.standardDecorators.dtDdWrapper" title="17.7.3. Zend_Form_Decorator_DtDdWrapper">DtDdWrapper</a>
            decorators to render the element. No label decorator is used, as the
            button label is used when rendering the element; also, typically,
            you will not associate errors with a submit element.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.text"></a>17.6.13. Zend_Form_Element_Text</h3></div></div></div>
<p>
            By far the most prevalent type of form element is the text element,
            allowing for limited text entry; it's an ideal element for most data
            entry. <code class="code">Zend_Form_Element_Text</code> simply uses the
            'formText' view helper to display the element.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.form.standardElements.textarea"></a>17.6.14. Zend_Form_Element_Textarea</h3></div></div></div>
<p>
            Textareas are used when large quantities of text are expected, and
            place no limits on the amount of text submitted (other than maximum
            size limits as dictated by your server or PHP).
            <code class="code">Zend_Form_Element_Textarea</code> uses the 'textArea' view
            helper to display such elements, placing the value as the content of
            the element.
        </p>
</div>
</div>
<div class="navfooter"><table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="zend.form.decorators.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="zend.form.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="zend.form.standardDecorators.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">17.5. Creating Custom Form Markup Using Zend_Form_Decorator </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> 17.7. Standard Form Decorators Shipped With Zend Framework</td>
</tr>
</table></div>
<div class="revinfo"></div>
</body>
</html>
